# ESP32-S3 API 参考

```{admonition} 本文引用的文件
:class: note

- `ai_cloud.py`
- `ATGM336H_5N.py`
- `max30102.py`
- `xgo.py`
- `lv_utils.py`
- `xunfei.py`
- `espnow.py`
- `hrcalc.py`
```

## 产品概述
本参考聚焦于 ESP32-S3 产品线（掌控板3.0、乐动掌控2.0等）的专属API，重点覆盖新增模块与能力：AI云端交互、GNSS定位（北斗/GPS）、心率血氧传感、机器狗控制、LVGL事件循环工具，以及与ESP32版API的差异要点。文档面向K12创客教育场景，帮助开发者快速理解各模块职责、调用方式与注意事项。

## 核心业务流程
- AI语音识别与问答流程（百度语音+文心大模型）
  - 录音文件转Base64并请求百度语音识别接口，返回文本；再调用文心对话接口获取回答。
  - 关键节点：鉴权token获取、音频文件读取、HTTP POST请求、JSON解析。
- GNSS定位数据读取与解析流程（ATGM336H）
  - UART读取原始NMEA帧，过滤RMC与BDGSA段，解析时间、经纬度、速度、日期及卫星信息。
  - 关键节点：串口缓冲、ASCII解码容错、字段截取与校验、数据有效性标志。
- 心率血氧测量流程（MAX30102 + hrcalc）
  - I2C初始化设备，周期性读取FIFO红/红外光值，使用算法计算HR与SpO2，输出有效结果或错误码。
  - 关键节点：寄存器配置、FIFO采样、峰值检测、比值计算与阈值判定。
- 机器狗控制流程（XGO）
  - 通过串口协议发送指令控制移动、姿态、动作、舵机角度、电池与固件信息等。
  - 关键节点：命令封装与校验、参数范围映射、响应解包与超时处理。
- LVGL事件循环流程
  - 基于定时器或uasyncio驱动LVGL tick与任务处理，支持同步/异步刷新回调。
  - 关键节点：lv.init、tick_inc、task_handler、异常捕获与自动停止。

```text
sequenceDiagram
participant App as "应用"
participant AI as "AI云端模块"
participant HTTP as "网络请求"
App->>AI : 调用 get_text(录音文件)
AI->>HTTP : 获取访问令牌
HTTP-->>AI : 返回 token
AI->>HTTP : POST 语音识别接口
HTTP-->>AI : 返回识别结果
App->>AI : 调用 get_answer(文本)
AI->>HTTP : POST 文心对话接口
HTTP-->>AI : 返回回答文本
AI-->>App : 返回最终答案
```

**图表来源**
- `ai_cloud.py:18-24`
- `ai_cloud.py:69-92`
- `ai_cloud.py:94-122`

**章节来源**
- `ai_cloud.py:18-24`
- `ai_cloud.py:69-92`
- `ai_cloud.py:94-122`

## 功能模块清单
- AI云端模块（ai_cloud.py）
  - 职责：提供语音识别与文心问答的便捷接口，封装鉴权、HTTP请求与JSON解析。
  - 用户价值：简化云端AI集成，降低网络与协议复杂度。
  - 验收要点：token获取成功、识别结果正确、问答返回合理文本；异常时打印错误并抛出提示。
- GNSS定位模块（ATGM336H_5N.py）
  - 职责：UART读取NMEA数据，解析RMC与BDGSA，输出时间、经纬度、速度与日期。
  - 用户价值：为位置服务、轨迹记录、导航类项目提供基础定位能力。
  - 验收要点：能稳定读取RMC/BDGSA，解析出有效坐标与UTC时间，具备无效数据处理逻辑。
- 心率血氧模块（max30102.py + hrcalc.py）
  - 职责：I2C驱动MAX30102，采集PPG信号，计算心率与血氧浓度。
  - 用户价值：健康类项目的基础生理指标采集。
  - 验收要点：设备可扫描到，FIFO数据可读，HR/SpO2在合理范围内且带有效性标识。
- 机器狗控制模块（xgo.py）
  - 职责：通过串口协议控制XGO机器狗的运动、姿态、动作、舵机、电池与固件信息。
  - 用户价值：机器人教学与竞赛的核心控制库。
  - 验收要点：指令发送与响应校验通过，参数范围限制生效，读回数据准确。
- LVGL事件循环工具（lv_utils.py）
  - 职责：提供LVGL定时刷新与任务调度，支持同步/异步模式与异常处理。
  - 用户价值：统一GUI刷新机制，避免阻塞与内存分配问题。
  - 验收要点：lv.init后tick正常推进，task_handler执行，异常被捕获并安全停止。
- 讯飞语音模块（xunfei.py）
  - 职责：基于WebSocket实现语音识别（IAT）与语音合成（TTS），含鉴权签名。
  - 用户价值：在线语音能力扩展，适合语音交互项目。
  - 验收要点：WebSocket连接建立成功，音频流分段发送，识别结果拼接正确，TTS音频下载完成。
- ESP-NOW通信模块（espnow.py）
  - 职责：封装底层ESPNowBase，提供无连接短报文收发与迭代接收。
  - 用户价值：低功耗、低延迟的局域网通信方案。
  - 验收要点：发送与接收字节流正确，超时处理合理，迭代器模式可用。

**章节来源**
- `ai_cloud.py:18-24`
- `ai_cloud.py:69-92`
- `ai_cloud.py:94-122`
- `ATGM336H_5N.py:29-165`
- `ATGM336H_5N.py:198-388`
- `max30102.py:39-168`
- `hrcalc.py:13-105`
- `xgo.py:123-787`
- `lv_utils.py:43-142`
- `xunfei.py:65-229`
- `espnow.py:6-41`

## 数据与状态
- AI云端模块
  - 输入：录音文件路径、文本内容；配置：API_KEY/SECRET_KEY。
  - 输出：识别文本、问答回答；状态：token缓存、请求头设置。
  - 边界：网络可达性、云端限流与鉴权失败需重试或降级。
- GNSS定位模块
  - 输入：UART原始NMEA帧；状态：是否解码、是否解析、数据有效性标志。
  - 输出：UTC时间、经纬度（度分格式与十进制）、速度（节与km/h）、日期、卫星PRN列表。
  - 边界：非ASCII字符容错、RMC/BDGSA缺失时的空值处理。
- 心率血氧模块
  - 输入：I2C FIFO红/红外光值序列；状态：设备初始化、测量进行中。
  - 输出：HR（bpm）、SpO2（%）及有效性；内部状态：ir_D/red_D均值。
  - 边界：采样时长约30秒，异常时返回None或错误码。
- 机器狗控制模块
  - 输入：运动方向/步数、姿态角度、动作ID、舵机角度、电池查询等。
  - 输出：固件版本、电池电量、IMU角度（roll/pitch/yaw）、舵机角度。
  - 状态：协议帧解析状态机、超时与校验失败处理。
- LVGL事件循环
  - 输入：频率、定时器ID、刷新回调、异常处理器。
  - 输出：LVGL任务处理、UI刷新；状态：运行中/已停止、嵌套计数。
  - 边界：缺少uasyncio时仅支持同步模式；异常时自动deinit。
- 讯飞语音模块
  - 输入：音频文件或文本；状态：WebSocket连接、消息帧状态（首帧/中间帧/末帧）。
  - 输出：识别结果字符串、TTS音频文件。
  - 边界：鉴权签名生成、RTC时间获取、网络稳定性。
- ESP-NOW模块
  - 输入：目标地址、数据长度、格式；状态：接收缓冲区、迭代器状态。
  - 输出：字节流或浮点数（可选格式化）；状态：超时与空结果。
  - 边界：MAX_DATA_LEN限制、字节序转换。

**章节来源**
- `ai_cloud.py:18-24`
- `ai_cloud.py:69-92`
- `ai_cloud.py:94-122`
- `ATGM336H_5N.py:29-165`
- `ATGM336H_5N.py:198-388`
- `max30102.py:39-168`
- `hrcalc.py:13-105`
- `xgo.py:123-787`
- `lv_utils.py:43-142`
- `xunfei.py:65-229`
- `espnow.py:6-41`

## 关键约束与边界
- 网络与云端依赖
  - AI云端与讯飞语音均依赖WiFi与互联网，需确保网络连通与鉴权配置正确；云端限流或故障时应做重试与降级策略。
- 硬件资源与引脚
  - GNSS使用UART（默认UART1，TX/RX可配），注意引脚冲突；MAX30102使用I2C，需确认设备地址与总线空闲。
  - XGO通过串口通信，注意波特率与协议帧校验；LVGL事件循环占用定时器或协程资源。
- 数据有效性与容错
  - GNSS数据需检查RMC有效性标志，缺失时返回占位值；心率血氧测量需要稳定接触与足够采样时长。
  - LVGL事件循环在异常时自动停止，避免死锁；ESP-NOW接收有超时与空结果处理。
- 性能与实时性
  - 心率血氧测量约30秒，期间应避免阻塞其他任务；LVGL刷新频率建议根据屏幕与任务负载调整。
  - XGO指令发送间隔与最小时间参数影响运动平滑性，需按实际硬件调优。

**章节来源**
- `ai_cloud.py:69-92`
- `xunfei.py:65-229`
- `ATGM336H_5N.py:29-165`
- `max30102.py:133-168`
- `xgo.py:610-688`
- `lv_utils.py:43-142`
- `espnow.py:14-41`